home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / source / tracker-4.13.lha / tracker / extern.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-02-15  |  14.9 KB  |  527 lines
  1. /* extern.h 
  2.     vi:ts=3 sw=3:
  3.  */
  4.  
  5. /* $Id: extern.h,v 4.9 1995/02/14 04:02:28 espie Exp $
  6.  * $Log: extern.h,v $
  7.  * Revision 4.9  1995/02/14  04:02:28  espie
  8.  * Changed amiga prototype.
  9.  *
  10.  * Revision 4.9  1995/02/14  04:02:28  espie
  11.  * Changed amiga prototype.
  12.  *
  13.  * Revision 4.8  1995/02/06  14:50:47  espie
  14.  * Changed sample_info.
  15.  *
  16.  * Revision 4.8  1995/02/06  14:50:47  espie
  17.  * Changed sample_info.
  18.  *
  19.  * Revision 4.7  1995/02/01  20:41:45  espie
  20.  * Added color.
  21.  *
  22.  * Revision 4.6  1995/02/01  16:39:04  espie
  23.  * Added LEFT_SIDE/RIGHT_SIDE defines (finally !)
  24.  *
  25.  * Revision 4.6  1995/02/01  16:39:04  espie
  26.  * Added LEFT_SIDE/RIGHT_SIDE defines (finally !)
  27.  *
  28.  * Revision 4.1  1994/02/04  14:54:08  espie
  29.  * Fixed up ansi C stupid bug.
  30.  * Lots of new proto for all functions.
  31.  * Generalized open.c.
  32.  * Comments.
  33.  * Added checkbrk.
  34.  * General cleanup.
  35.  * Suppressed some unused code.
  36.  * Better portability.
  37.  * Removed init_display.
  38.  * No more reentrency problems with INIT_ONCE.
  39.  * Protos for ui: notice, info, scroller, pattern display.
  40.  * Mostly working.
  41.  * Just dies with a guru.
  42.  * Plus timing problems at start.
  43.  * New prototypes.
  44.  * Initial revision
  45.  *
  46.  * Revision 3.15  1993/12/04  16:12:50  espie
  47.  * Amiga support.
  48.  * Added bg/fg test.
  49.  * stty_sane.
  50.  * New audio functions.
  51.  * Simplified delay_pattern.
  52.  * Protracker commands.
  53.  * New release.
  54.  *
  55.  * Revision 2.19  1992/11/17  17:06:25  espie
  56.  * Lots of new functions to account for new interface.
  57.  * open_file support.
  58.  * Separated mix/stereo stuff.
  59.  * Added possibility to get back to MONO for the sgi.
  60.  * Added stereo capabilities to the indigo version.
  61.  * Added some new song types to automatize the choice process.
  62.  * Moved resampling to audio, added prototype.
  63.  * Added SAMPLE_FAULT, for trying to play
  64.  * a note without a sample (not really an error).
  65.  *
  66.  * Revision 1.7  1991/11/08  14:25:55  espie
  67.  * Modified audio prototype so that you can change
  68.  * frequency.
  69.  * Added prototype for release_song.
  70.  * Added arpeggio effect.
  71.  * Added entries for new effects.
  72.  * Added entries for commands.c.
  73.  */
  74.  
  75.  
  76.  
  77. /* resample.c */
  78. #define ACCURACY 12
  79. #define fix_to_int(x) ((x) >> ACCURACY)
  80. #define int_to_fix(x) ((x) << ACCURACY)
  81. #define fractional_part(x) ((x) & (total_step - 1))
  82. #define total_step     (1 << ACCURACY)
  83.  
  84.  
  85. /* release_audio_channels:
  86.  * free every audio channel previously allocated
  87.  */
  88. XT void release_audio_channels P((void));
  89.  
  90.  
  91. #define LEFT_SIDE 0
  92. #define RIGHT_SIDE 1
  93. #define BASE_AUDIO 20
  94. #define AUDIO_SIDE (BASE_AUDIO)
  95. /* chan = new_channel_tag_list(prop):
  96.  * allocates a new channel for the current song
  97.  * properties: AUDIO_SIDE LEFT_SIDE (default)/RIGHT_SIDE
  98.  */
  99. XT struct audio_channel *new_channel_tag_list P((struct tag *prop));
  100.  
  101. /* init_tables(oversample, frequency):
  102.  * precomputes the step_table and the pitch_table
  103.  * according to the desired oversample and frequency.
  104.  * This is static, you can call it again whenever you want.
  105.  * Adjust the currently used audio channels if needed.
  106.  */
  107. XT void init_tables P((int oversample, int frequency));
  108.  
  109. /* resample(oversample, number):
  110.  * send number samples out computed according
  111.  * to the current state of channels
  112.  * and oversample.
  113.  */
  114. XT void resample P((int oversample, int number));
  115.  
  116. /* play_note(au, samp, pitch)
  117.  * set audio channel au to play samp at pitch
  118.  */
  119. XT void play_note P((struct audio_channel *au, struct sample_info *samp, \
  120. int pitch));
  121.  
  122. /* set_play_pitch(au, pitch):
  123.  * set channel au to play at pitch pitch
  124.  */
  125. XT void set_play_pitch P((struct audio_channel *au, int pitch));
  126.  
  127. /* set_play_volume(au, volume):
  128.  * set channel au to play at volume volume
  129.  */
  130. XT void set_play_volume P((struct audio_channel *au, int volume));
  131.  
  132. /* set_play_position(au, pos):
  133.  * set position in sample for channel au at given offset
  134.  */
  135. XT void set_play_position P((struct audio_channel *au, int pos));
  136.  
  137. /* empty.c */
  138. /* empty = empty_sample():
  139.  * returns a suitable empty sample
  140.  */
  141. XT struct sample_info *empty_sample P((void));
  142.  
  143. /* automaton.c */
  144. /* init_automaton(a, song, start):
  145.  * put the automaton a in the right state to play song from pattern start.
  146.  */
  147. XT void init_automaton P((struct automaton *a, struct song *song, int start));
  148.  
  149. /* next_tick(a):
  150.  * set up everything for the next tick.
  151.  */
  152. XT void next_tick P((struct automaton *a));
  153.  
  154.  
  155. /* commands.c */
  156. /* init_effects(): sets up all data for the effects */
  157. /* (not set up as auto_init due to huge overhead) */
  158. XT void init_effects P((void (*table[])()));
  159.  
  160. /* do_nothing: this is the default behavior for an effect.
  161.  */
  162. XT void do_nothing P((struct channel *ch));
  163.  
  164.  
  165. /* dump_song.c */
  166. /* dump_song(s): 
  167.  * displays some information pertinent to the given 
  168.  * song s.
  169.  */
  170. XT void dump_song P((struct song *song));
  171.  
  172.  
  173. /* display.c */
  174.  
  175. /* dump_event(ch, e): dump event e as occuring on channel ch
  176.  */
  177. XT void dump_event P((struct channel *ch, struct event *e));
  178. XT void dump_delimiter P((void));
  179.  
  180.  
  181. /* main.c */
  182.  
  183. #define OLD 0
  184. #define NEW 1
  185. /* special new type: for when we try to read it as both types.
  186.  */
  187. #define BOTH 2
  188. /* special type: does not check the signature */
  189. #define NEW_NO_CHECK 3
  190.  
  191.  
  192. /* error types. Everything is centralized,
  193.  * and we check in some places (see st_read, player and main)
  194.  * that there was no error. Additionnally signal traps work
  195.  * that way too.
  196.  */
  197.  
  198. /* normal state */
  199. #define NONE 0  
  200. /* read error */
  201. #define FILE_TOO_SHORT 1
  202. #define CORRUPT_FILE 2
  203. /* trap error: goto next song right now */
  204. #define NEXT_SONG 3
  205. /* run time problem */
  206. #define FAULT 4
  207. /* the song has ended */
  208. #define ENDED 5
  209. /* unrecoverable problem: typically, trying to 
  210.  * jump to nowhere land.
  211.  */
  212. #define UNRECOVERABLE 6
  213. /* Missing sample. Very common error, not too serious. */
  214. #define SAMPLE_FAULT 7
  215. /* New */
  216. #define PREVIOUS_SONG 8
  217. #define OUT_OF_MEM 9
  218. XT int error;
  219.  
  220. /* notes.c */
  221. #define NUMBER_NOTES 120
  222. #define NUMBER_FINETUNES 17
  223. XT short pitch_table[NUMBER_NOTES][NUMBER_FINETUNES];    /* 120 * 17 = big ! */
  224.  
  225. /* note = find_note(pitch):
  226.  * find note corresponding to a given pitch. 
  227.  */
  228. XT int find_note P((int pitch));
  229.  
  230. /* oldtranspose = transpose_song(song, newtranspose):
  231.  * tranpose song to a new pitch
  232.  */
  233. XT int transpose_song P((struct song *song, int newtranspose));
  234.  
  235. /* name = name_of_note(note):
  236.  * name of the note. Warning! This name is only valid
  237.  * until a new call to name_of_note.
  238.  */
  239. XT char *name_of_note P((int note));
  240.  
  241.  
  242.  
  243.  
  244.  
  245. /* open.c */
  246. /* handle = open_file(filename, mode, path):
  247.  * transparently open a compressed file.
  248.  */
  249. XT struct exfile *open_file P((char *fname, char *fmode, char *path));
  250.  
  251. /* close_file(handle):
  252.  * close a file that was opened with open_file.
  253.  */
  254. XT void close_file P((struct exfile *file));
  255.  
  256. XT int getc_file P((struct exfile *file));
  257. XT int tell_file P((struct exfile *file));
  258. XT int read_file P((void *p, int s, int n, struct exfile *file));
  259. XT void rewind_file P((struct exfile *file));
  260.  
  261.  
  262.  
  263.  
  264. /* player.c */
  265.  
  266. /* reset_note(ch, note, pitch):
  267.  * set channel ch to play note at pitch pitch
  268.  */
  269. XT void reset_note P((struct channel *ch, int note, int pitch));
  270.  
  271. /* set_current_pitch(ch, pitch):
  272.  * set ch to play at pitch pitch
  273.  */
  274. XT void set_current_pitch P((struct channel *ch, int pitch));
  275.  
  276. /* set_current_volume(ch, volume):
  277.  * set channel ch to play at volume volume
  278.  */
  279. XT void set_current_volume P((struct channel *ch, int volume));
  280.  
  281. /* set_position(ch, pos):
  282.  * set position in sample for current channel at given offset
  283.  */
  284. XT void set_position P((struct channel *ch, int pos));
  285.  
  286. /* init_player(oversample, frequency):
  287.  * sets up the player for a given oversample and
  288.  * output frequency.
  289.  * Note: we can call init_player again to change oversample and
  290.  * frequency.
  291.  */
  292. XT void init_player P((int o, int f));
  293.  
  294. /* play_song(song, start):
  295.  * play the song.
  296.  */
  297. XT struct tag *play_song P((struct song *song, int start));
  298. /* returns tags as shown further down in get_ui */
  299.  
  300.  
  301.  
  302. /* st_read.c */
  303. /* s = read_song(f, type):
  304.  * tries to read f as a song of type NEW/OLD.
  305.  * returns NULL (and an error) if it doesn't work.
  306.  * Returns a dynamic song structure if successful.
  307.  */
  308. XT struct song *read_song P((struct exfile *f, int type));
  309.  
  310. /* release_song(s):
  311.  * release all the memory song occupies.
  312.  */
  313. XT void release_song P((struct song *song));
  314.  
  315.  
  316.  
  317. /* setup_audio.c */
  318. /* setup_audio(ask_freq, stereo, oversample):
  319.  * setup the audio output with these values 
  320.  */
  321. XT void setup_audio P((int f, int s, int o));
  322. /* do_close_audio():
  323.  * close audio only if needed
  324.  */
  325. XT void do_close_audio P((void));
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333. /* audio.c */
  334. /* frequency = open_audio(f, s):
  335.  * try to open audio with a sampling rate of f, and eventually stereo.
  336.  * We get the real frequency back. If we ask for 0, we
  337.  * get the ``preferred'' frequency.
  338.  * Note: we have to close_audio() before we can open_audio() again.
  339.  * Note: even if we don't ask for stereo, we still have to give a
  340.  * right and left sample.
  341.  */
  342. XT int open_audio P((int f, int s));
  343. /* close_audio():
  344.  * returns the audio to the system control, doing necessary
  345.  * cleanup
  346.  */
  347. XT void close_audio P((void));
  348. /* set_mix(percent): set mix channels level.
  349.  * 0: spatial stereo. 100: mono.
  350.  */
  351. XT void set_mix P((int percent));
  352.  
  353. /* output_samples(l, r): outputs a pair of stereo samples.
  354.  * Samples are 23 bits signed.
  355.  */
  356. XT void output_samples P((int left, int right));
  357.  
  358. /* flush_buffer(): call from time to time, because buffering
  359.  * is done by the program to get better (?) performance.
  360.  */
  361. XT void flush_buffer P((void));
  362.  
  363. /* discard_buffer(): try to get rid of the buffer contents
  364.  */
  365. XT void discard_buffer P((void));
  366.  
  367. /* new_freq = update_frequency():
  368.  * if !0, frequency changed and playing should be updated accordingly
  369.  */
  370. XT int update_frequency P((void));
  371.  
  372. /* set_synchro(boolean):
  373.  * try to synchronize audio output by using a smaller buffer
  374.  */
  375. XT void set_synchro P((int s));
  376.  
  377. #ifdef SPECIAL_SAMPLE_MEMORY
  378. XT GENERIC alloc_sample P((int len));
  379. XT void free_sample P((GENERIC s));
  380. XT int obtain_sample P((GENERIC start, int l, struct exfile *f));
  381.  
  382. #else
  383. #define alloc_sample(len)        calloc(len, 1)
  384. #define free_sample(sample)        free(sample)
  385. #define obtain_sample(start, l, f)    read_file(start, 1, l, f)
  386. #endif
  387.  
  388.  
  389.  
  390. /* tools.c */
  391. /* v = read_env(name, default):
  392.  * read a scalar value in the environment
  393.  */
  394. XT int read_env P((char *name, int def));
  395.  
  396.  
  397.  
  398.  
  399. /* autoinit.c */
  400. /* used for decentralizing initialization/termination of various
  401.  * system routines
  402.  */
  403.  
  404. /* end_all(s): the program must exit now, after displaying s to the user, usually 
  405.  * through notice and calling all stacked at_end() functions. s may be 0 for normal
  406.  * exit. DO NOT use exit() anywhere in tracker but end_all() instead.
  407.  */
  408. XT void end_all P((char *s));
  409.  
  410. /* at_end(cleanup): stack cleanup to be called at program's termination
  411.  */
  412. XT void at_end P((void (*cleanup)(void)));
  413.  
  414. /* INIT_ONCE: macro for autoinitialization of routines.
  415.  * modules that need an init routine should LOCAL void INIT = init_routine,
  416.  * and add INIT_ONCE; at EVERY possible first entry point for their routine.
  417.  * (I mean every, don't try to second-guess me !)
  418.  */
  419. #define INIT_ONCE        if (INIT)    {void (*func)P((void)) = INIT; INIT = 0; (*func)();}
  420.  
  421.  
  422. /* $(UI)/ui.c */
  423. /* see unix/ui.c for the general unix implementation.
  424.  * The old may_getchar() has been replaced by the tag-based
  425.  * get_ui
  426.  */
  427. /* get_ui(): returns an array of tags that reflect the current user-interface
  428.  * actions. Unknown tags WILL be ignored.
  429.  * Note that get_ui will be called about once every tick, providing a poor man's
  430.  * timer to the interface writer if needed to code multiple actions on the same
  431.  * user-input. See unix/termio.c for a good example.
  432.  * see amiga/ui.c for the correct way to do it when you have a real timer.
  433.  *
  434.  * VERY IMPORTANT: who do the tags belong to ?
  435.  *    as a general rule, result (and their values) MUST only be considered
  436.  *    valid between two calls to get_ui ! Be careful to call get_ui ONLY at
  437.  *    reasonable places.
  438.  *    One exception: structures that are dynamically allocated (like UI_LOAD_SONG
  439.  *    values) will ONLY get freed when you ask for it !
  440.  */
  441. XT struct tag *get_ui P((void));
  442. #define BASE_UI 10
  443. #define UI_NEXT_SONG    (BASE_UI)            /* load next song */
  444. #define UI_PREVIOUS_SONG (BASE_UI + 1)    /* load previous song */
  445. #define UI_LOAD_SONG (BASE_UI + 2)        /* load song. Name as value */
  446. #define UI_SET_BPM (BASE_UI + 3)          /* set beat per minute to value */
  447. #define UI_JUMP_TO_PATTERN (BASE_UI + 4)  /* jump to pattern #value. Use display_pattern to
  448.                                            * keep in sync with the player
  449.                                            */
  450. #define UI_RESTART (BASE_UI + 5)          /* restart current song. Not quite jump to 0 */
  451. #define UI_QUIT (BASE_UI + 6)             /* need I say more ? */
  452. #define UI_DISPLAY (BASE_UI + 7)          /* status of scrolling window: true or false */
  453.  
  454.  
  455. /* player.c translates the get_ui() tags in a standard way.
  456.  * Actually it doesn't translate anything right now...
  457.  */
  458. #define BASE_PLAY 20
  459. #define PLAY_NEXT_SONG UI_NEXT_SONG
  460. #define PLAY_PREVIOUS_SONG UI_PREVIOUS_SONG
  461. #define PLAY_LOAD_SONG UI_LOAD_SONG
  462.  
  463. #define PLAY_ERROR BASE_PLAY
  464.  
  465. /* Most of these functions are information display function.
  466.  * A correct implementation should heed run_in_fg() if needed
  467.  */
  468.  
  469. /* notice(s): important message for the user (terminal error maybe).
  470.  * take extra pain to make it apparent even if run in background
  471.  */
  472. XT void notice P((char *s));
  473.  
  474. /* status(s): some indication of the system current status... 
  475.  * Used for fleeing error messages too. 
  476.  * s = 0 is valid and indicates return to the default status.
  477.  */
  478. XT void status P((char *s));
  479.  
  480. /* begin_info: open a logical information window.
  481.  * returns 0 if the window couldn't be opened.
  482.  * A NULL window shouldn't be used, but don't count on it !
  483.  */
  484. XT GENERIC begin_info P((char *title));
  485. /* info(handle, line): add a line to the info window,
  486.  * completing the current line if applicable
  487.  */
  488. XT void info P((GENERIC handle, char *line));
  489. /* infos(handle, line): add to the current line of the info window
  490.  */
  491. XT void infos P((GENERIC handle, char *s));
  492. /* end_info(handle): this window is complete...
  493.  */
  494. XT void end_info P((GENERIC handle));
  495.  
  496. /* Scrolling score display:
  497.  * new_scroll() returns a writable buffer of 4*14-1 characters in
  498.  * which the program (usually display.c) will write what it wills.
  499.  * It can return 0 if not applicable.
  500.  */
  501. XT char *new_scroll P((void));
  502.  
  503. /* scroll: returns this scrolling line to the program. Note that
  504.  * scroll doesn't take any argument, and implies calls to new_scroll/scroll
  505.  * are paired. After a call to scroll, the last pointer returned by new_scroll
  506.  * should be considered invalid !
  507.  */
  508. XT void scroll P((void));
  509.  
  510. /* display_pattern(current, total, real): we are at current/total(real) 
  511.  * in the current song
  512.  * may be used as a poor man's timer.
  513.  */
  514. XT void display_pattern P((int current, int total, int real));
  515.  
  516. /* song_title(s): the current song title is s.
  517.  * ui implementors: Don't count on this pointer remaining valid AFTER the call,
  518.  * make a copy if needed
  519.  */
  520. XT void song_title P((char *s));
  521.  
  522. /* boolean checkbrk():
  523.  * check whether a break occured and we should end right now.
  524.  * Call it often enough (like when loading songs and stuff)
  525.  */
  526. XT int checkbrk P((void));
  527.